home *** CD-ROM | disk | FTP | other *** search
/ Shareware Grab Bag / Shareware Grab Bag.iso / 007 / basaid50.arc / BASICAID.DOC next >
Text File  |  1987-02-21  |  22KB  |  561 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.                              BASICAID
  10.  
  11.  
  12.                    THE BASIC PROGRAMMERS FRIEND
  13.  
  14.  
  15.                            VERSION 5.0
  16.                             FEB ,1987
  17.  
  18.  
  19.  
  20.  
  21.  
  22.  
  23.                       All RIGHTS RESERVED
  24.  
  25.  
  26.                   (SUPERSEDES V4.0 dated 1986)
  27.  
  28.  
  29.  
  30.  
  31.  
  32.  
  33.  
  34.   COPYRIGHT (c) 1983, 1984, 1985, 1986, 1987 by Downlink Systems Inc.
  35.  
  36.  
  37.  
  38.  
  39.  
  40.   This document describes the BASICAID Basic source enhancement system,
  41.   version 5.00, which was created by Downlink Sys. in FEBRUARY of 1987.
  42.  
  43.  
  44.                                   INTRODUCTION
  45.  
  46.  
  47.  
  48.      BASICAID     is the copyrighted property of Downlink Sys. Inc.
  49.      You are granted a limited license to use , and to copy it and
  50.      distribute it, provided that the following conditions are met:
  51.  
  52.      1) No fee may be charged for such copying and distribution.
  53.  
  54.      2) BASICAID       may ONLY be distributed in its original, unmodified
  55.         state.
  56.  
  57.  
  58.      Contributions for the use of this program will be appreciated, and
  59.      should be sent to:
  60.  
  61.                              Downlink Systems Inc.
  62.  
  63.                              c/o D. Conner
  64.                              1377 K. STREET N.W.
  65.                              SUITE 189
  66.                              WASHINGTON D.C.
  67.                                              20005
  68.  
  69.      You may not use this product in a commercial environment or a
  70.      governmental organization without paying a license fee of $25.
  71.      Site licenses and commercial distribution licenses are available.
  72.      A program disk and printed documentation are available for $25.
  73.      See the order form in the back of this manual for more details.
  74.  
  75.  
  76.      BASICAID       is user supported software.  This means that you may
  77.      copy the shareware version freely and give the copies away to anyone
  78.      you wish, at no cost. They in turn are requested to send in a contri-
  79.      bution if they decide to use it.
  80.  
  81.      The user supported software concept (often referred to as shareware)
  82.      is an attempt to provide software at low cost.  The cost of offering a
  83.      new product by conventional means is staggering, and hence dissuades
  84.      many independent authors and small companies from developing and
  85.      promoting their ideas.  User supported software is an attempt to
  86.      develop a new marketing channel, where products can be introduced at
  87.      low cost.
  88.  
  89.      If user supported software works, then everyone will benefit.  The
  90.      user will benefit by receiving quality products at low cost, and by
  91.      being able to "test drive" software thoroughly before purchasing it.
  92.      The author benefits by being able to enter the commercial software
  93.      arena without first needing large sources of venture capital.
  94.  
  95.      But it can only work with your support.  We're not just talking about
  96.      BASICAID, but about all user supported software.  If you obtain a user
  97.      supported program from a friend or colleague, and are still using it
  98.      after a couple of weeks, then it is obviously worth something to you,
  99.      and a contribution should be sent. Upon receipt of a contribution,
  100.      you become a registered user and will receive a "full" feature, serial-
  101.      ized version of BASICAID.
  102.  
  103.  
  104.  
  105.  This is a complete rewrite of version 4.x. BASICAID has been rewritten in
  106. QUICK BASIC 2.00. To support both monochrome and CGA monitors, the user
  107. interface has been changed to use an enhanced version of BASWIND window
  108. routines. These WINDOW routines hopefully provide a common interface
  109. across monitor types. BASICAID takes advantage of pop up, pop over,
  110. pop list and general window type formats. The QUICK BASIC screen format has
  111. been followed. This was not initially intentionally done, but it evolved
  112. toward and to this "look and somewhat feel". There is no mouse support,
  113. at this time, for the window interface, but look for it later.
  114.  
  115.  
  116.  
  117.                         !! NOTE NOTE NOTE !!
  118.  
  119. Version 5.0 now allows  ALL  forms of stored basic programs to be used as input.
  120.  
  121. ** The option to additionally process protected BASIC programs is available **
  122.                  ------------------------------
  123.                    ** only to Registered users **
  124.                       ------------------------
  125.  
  126.        !! This is not a demo version, its an rewrite of 4.0 !!
  127.  
  128.  
  129.  
  130.  Therefore the source is no longer being distributed, due to the confidential
  131. nature of the logic that duplicates the MS BASIC decryption routines!
  132.  
  133.  However, the decryption routine(s) are for sale for inclusions in your
  134. works, at a price to be negotiated at the time of sale.
  135.  
  136.  This version , 5.0, is now compatible with MS-BASIC 2.0 COMPILER and
  137. IBM BASIC 2.0 COMPILER, in that any program that will run under the DOS
  138. BASIC INTERPRETER can be processed by 'BASICAID'. Also command line
  139. RUNTIME options may be entered.
  140.  
  141.  
  142.  
  143.  
  144.   Editorial comment:
  145.  
  146.        Contrary to PC-SIG'S statement that we Shareware authors make
  147.       big bucks, Shareware as it exists is NOT working. We find that
  148.       we to are guilty of the same abuse of other Shareware products.
  149.  
  150.        This attitude that PC-SIG and others give of Shareware being
  151.       public domain is totally false and is/will cause Shareware
  152.       software to cease to exist or take on a 'restricted usage'
  153.       form. This is what we have been forced to do with past and
  154.       all future Shareware products. A 'restricted usage' form of
  155.       software will be released. All the features will be included
  156.       but in a form as to entice users to register to get all the
  157.       whistles, bells and additional features that are worth the
  158.       registration fee.
  159.  
  160.        As an example, just the other day we had a MAJOR hardware vendor
  161.       come by to give a demo of some of their products. They had the
  162.       shareware comm program, Qmodem, listed in their document as a
  163.       "public domain" freebee  that they could give us to use with
  164.       their async device. Can you believe the mentality of such a
  165.       LARGE company. Obviously the 'something for nothing' approach
  166.       to shareware is becoming the standard way of thinking.
  167.  
  168.        We believe in the free exchange of ideas for intellectual advance.
  169.       We got to the power user level with the help of all the "public
  170.       domain" programs, source listings and free exchange of information
  171.       , and that is why we have tried to provide source to all our
  172.       contributions to PD also.
  173.  
  174.  
  175.                        !!    END COMMENT !!
  176.  
  177.  
  178.  
  179.  
  180.    Have you ever acquired a basic program from a friend and spent a lot of
  181. time just trying to untangle the program logic and statements, of course you
  182. have.
  183.  
  184.   Since each persons programming style is different, such as spacing, inden-
  185. tation and such, you could use your time better if all programs were about
  186. the same style.
  187.  
  188.    Are you an optimization and speed nut, as we are, especially when running
  189. a program under the interpreter. We don't like to wait a second longer than
  190. necessary. Of course by now we use the BASIC COMPILER as much as possible,
  191. since we would rather wait 2 minutes than have to wait 20 minutes to see
  192. the results of our lost sleep.
  193.  
  194.    We have seen several packages , not all with the same functions or
  195. range,selling from 20 to 80 dollars. Well this is several years worth of
  196. work,to you for free ,if you desire.
  197.  
  198.    As a basic overview the program will, compress,a basic program and remove
  199. remarks, expand a program by that we mean it will separate multiple statements
  200. per basic line into one or more statements, generate cross references on
  201. program variables and basic reserved words, and probably the most important
  202. will generate a cross reference showing all references to a specific line number
  203. that was referenced by a GOTO,GOSUB,ELSE,THEN,ERL,RESTORE OR RESUME statement.
  204.  
  205.  You can then find all variables, areas of code and such that are not
  206. referenced (and remove for storage savings) as well as on overview of
  207. program flow to find out how the program got to a specific line number.
  208.  
  209.  
  210.  
  211.  
  212.    EACH FUNCTIONAL OPTION OF THE PROGRAM IS DISCUSSED BELOW:
  213.  
  214.  
  215.       1).  EXPAND A BASIC PROGRAM
  216.            ----------------------
  217.  
  218.           Will expand a compressed program, one that has multiple
  219.         BASIC statements per line, separated by a ":" into one or
  220.         more uniquely numbered basic lines with one or more statements
  221.         per line.
  222.  
  223.           During the expanding some text compression will be done,
  224.         to remove extraneous spaces and such.
  225.  
  226.           Also an expanded listing can be requested, that will be printed
  227.         during the expansion.
  228.  
  229.           An expanded, output disk file, called "TEMPFILE.BAS" will
  230.         be created also. Rename the "TEMPFILE.BAS" if you want to save
  231.         it as the new version of your program.
  232.  
  233.           Note that the input basic program being expanded must be
  234.         sufficiently sequenced to allow the insertion of new lines
  235.         or the program will end with such a message. For example,if
  236.         there are 7 Basic statements on a line, separated by ":",
  237.         then if the original program was numbered by 5'S, the program
  238.         will separate the line into 6 more BASIC lines each with a
  239.         line number 1 greater than the previous line number.
  240.  
  241.           If you are processing an unnumbered BASIC program, or one
  242.         generated with unreferenced line numbers removed, a new line
  243.         number will be assigned to the unnumbered statement.
  244.  
  245.  
  246.  
  247.  
  248.       2).  COMPRESS A BASIC PROGRAM
  249.            ------------------------
  250.  
  251.           Will compress text (remove extraneous spaces and ":" and such)
  252.         as well as combine separate Basic lines into single lines with
  253.         as many logical statements per line as possible, and optionally
  254.         remove unreferenced line numbers from the compressed program
  255.         for use with the '/n' option of the BASIC compiler.
  256.  
  257.           By logical, we mean that any "REMARK" or "IF" or "DATA" statements
  258.         will not have lines added to them.
  259.  
  260.           Also any line referenced by a logic branch (GOTO,GOSUB..ECT) will
  261.         not be appended to any other line.
  262.  
  263.           You may request a listing of the compressed program be produced
  264.         during the compression run, but will slow the program down, unless
  265.         you have a print spooler installed.
  266.  
  267.           A compressed program disk file,  named "TEMPCOMP.BAS" is
  268.         created. Don't forget to rename "TEMPCOMP.BAS" if you want it
  269.         to be your new working version.
  270.  
  271.           Also  for version 2.0 (and above), an expanded file ,"TEMPFILE.BAS",
  272.         is also created to speed up the compress logic so that it will not
  273.         have to repeat the expansion logic and do as much error checking.
  274.  
  275.           Also with version 3.0 , and above, if during compression you request
  276.         that unreferenced line numbers be removed and the input basic program
  277.         already has unnumbered lines or multiple statements per line,the expand-
  278.         ed 'TEMPFILE' is written without line numbers on statements. What this
  279.         allows is that you may input a BASIC program that is not sufficiently
  280.         line numbered, so that during the temporary expansion process,the next
  281.         assigned incremental line number would conflict with an already coded
  282.         statement.
  283.  
  284.  
  285.  
  286.  
  287.  
  288.       3).  DATANAME AND RESERVED WORD CROSS REFERENCE
  289.            ------------------------------------------
  290.  
  291.           Will print a cross reference of Basic reserved words (such as
  292.          GOTO,PRINT,CALL..ect).
  293.  
  294.           Will print a cross reference (ascending on variable name) of all
  295.         user defined program variables.
  296.  
  297.  
  298.           This would be great for finding statements that define or modify
  299.         a variable.
  300.  
  301.           Any type of BASIC explicit variable state ,such as "!" or "#" or
  302.         "%" or "$" are ignored, only the variable name which consists of the
  303.         characters "A-Z","." and "0-9" are considered a unique name.
  304.  
  305.           You may have noticed that a variable name may be defined as being
  306.         one of several variable types. For example "A!" , "A#" , "A%", "A$"
  307.         , "A(" where "A(" is part of a "DIM", would all be recognized to the
  308.         cross reference as the same variable, but different by BASIC.
  309.  
  310.           By the way, you may define a variable with a terminating ".",
  311.         to also make it unique. For example "SPACES" is a reserved word,
  312.         but "SPACES." or "SPACES.$" or "SPACES.%" are processed by BASIC
  313.         as user defined variables.
  314.  
  315.           ALSO YOU COULD HAVE THE FOLLOWING CODE AND IT WOULD WORK:
  316.  
  317.                10 DIM A(10)
  318.                20 A=0
  319.                30 FOR A=1 TO 10
  320.                40 A(A)=A
  321.                50 NEXT A
  322.                60 END
  323.  
  324.            CONFUSING BUT NEAT, HUH.
  325.  
  326.  
  327.  
  328.  
  329.  
  330.        4).  LINE NUMBER CROSS REFERENCE
  331.            ---------------------------
  332.  
  333.           Will produce a (ascending by line number) cross reference,
  334.         listing any line number that was reference by another line number
  335.         and the referencing line number.
  336.  
  337.           This line number cross reference table is also used in the
  338.         option to compress a program. So that we don't throw away "REMARK"
  339.         lines that are branched to..
  340.  
  341.           You should use the listing produced to change the program logic
  342.         such that it does not branch to any non-executable BASIC statement.
  343.  
  344.           The "REMARKS" take up part of the "64K" that BASIC runs in, since
  345.         they are stored exactly as seen on the screen, not in any tokenized
  346.         form.
  347.  
  348.           Also not branching to "REMARKS" will allow the compress option
  349.         to remove the statement from the output compressed file.
  350.  
  351.           The BASIC compiler maintains a link list of line numbers. If you
  352.         do any type of "ON ERROR" checking in your BASIC program, each line
  353.         number , under these conditions , results in 4 or more bytes being
  354.         used in the ".OBJ" (object) file created by the compiler.You could see
  355.         why compressing the production version of the program could result in
  356.         memory and speed savings.A link list must be searched and if your
  357.         program was 500 lines, then (500 * (4+)) bytes must be used just to
  358.         maintain the line number list. Also if you run into the old "0 BYTES
  359.         REMAINING" message, compressing with the option to remove unreferenced
  360.         line numbers (especially with /E/X options) results in a large savings,
  361.         such that many times you can write a large program..
  362.  
  363.  
  364.  
  365.  
  366.     **************************************************************************
  367.  
  368.  
  369.     MACHINE REQUIREMENTS:   256K MINIMUM
  370.     ---------------------   BASIC 2.1+
  371.                             MS/IBM BASIC Compiler 2.0
  372.                             MONOCHROME/CGA COLOR DISPLAY
  373.                             DISK DRIVE [REAL AND/OR VIRTUAL(RAM)]
  374.                             EPSON PRINTER (OPTIONAL)
  375.  
  376.  
  377.     RUNNING THE PROGRAM:
  378.     --------------------
  379.  
  380.     From the DOS prompt type in > BASICAID   [optional parameters (see below)]
  381.  
  382.  
  383.  
  384.  
  385.  
  386.  
  387.    ************* BASIC COMPILER 2.0 SUPPORT **************
  388.  
  389.    COMMAND LINE RUNTIME OPTIONS:
  390.  
  391.     >BASICAID [OPTION,OPTION]
  392.  
  393.  
  394.             ;The [] indicates that options are not required, you do not
  395.              enter the '[]'.
  396.  
  397.             ;any option that is correctly entered will be processed and
  398.              you will not be prompted during program execution. This allows
  399.              a batch file with symbolic parameters!
  400.  
  401.        OPTION                                  FUNCTION
  402.        -------                  ---------------------------------------------
  403.        FILENAME=path\filename   This is the basic program to be processed,
  404.                                now full DOS path syntax is supported.
  405.  
  406.        OPTION=a-number          For 'a-number', substitute a value of 1 to 5,
  407.                                as appears on opening menu.
  408.  
  409.        TEMPDISK=drive           Specify the drive that the expanded file is to
  410.                                be created on.
  411.  
  412.        COMPDISK=drive           Specify the drive that the compressed file is
  413.                                to be created on.
  414.  
  415.        SORTDISK=drive           Specify the drive that the temporary line
  416.                                number cross-reference file is to be created on.
  417.  
  418.        LIST=YES/NO              Print a listing corresponding to function being
  419.                                performed. Used during 'compress' or 'expand'
  420.                                option.
  421.  
  422.        REMOVE=YES/NO            Remove unreferenced line numbers from the
  423.                                compressed program. note: basic compiler '/n'
  424.                                option required if this option selected.
  425.  
  426.        SHOW=YES/NO             Display line number being processed. Tests show
  427.                               that screen i/o is Basics slowest function, about
  428.                               25% decrease.
  429.  
  430.        NOBEEP=any-char.        Turn off most all whistles and beeps during
  431.                               processing. Added for quiet office, remote and
  432.                               batch unattended processing.
  433.  
  434.        ABORT=YES/NO           If any error condition, exit immediately to DOS
  435.                               or give operator chance to recover from error.
  436.  
  437.  
  438.  
  439.  
  440.        NOTE:
  441.             1). 'drive' is any valid DOS drive letter
  442.  
  443.             2). for  a `YES/NO' reply, only the first letter is checked.
  444.  
  445.             3). only valid options are scanned for on the command line.
  446.  
  447.             4). options are validated during processing, an invalid option
  448.                forces the program to get a valid reply from the keyboard
  449.                operator.
  450.  
  451.             5). if the program was invoked with command line options, program
  452.                will process without waiting for any replies,even 'press enter
  453.                to continue' prompts. This will allow complete unattended
  454.                batch operations.
  455.  
  456.             6). command line converted to all upper-case prior to scanning
  457.                for keywords.
  458.  
  459.             7). 'keywords' immediately followed by '='.
  460.  
  461.             8). all 'keywords' separate by ','.
  462.  
  463.  
  464.  
  465.  
  466.     ADDITIONAL COMMENTS:
  467.     --------------------
  468.  
  469.           The printed cross reference listing may be redirected to a disk
  470.          file. This way you can have a permanent cross reference file of
  471.          the basic program.
  472.  
  473.             *** note: The cross reference disk file option is only
  474.                      available to registered users.
  475.  
  476.             *** note: With the unregistered Shareware version there is
  477.                     a restriction on the number of references that the
  478.                     program can maintain. This is sufficient for most
  479.                     small-to-medium sized  Basic source programs.
  480.  
  481.  
  482.           This conversion and rewrite of BASICAID to QUICK BASIC 2.00 was
  483.          a time consuming effort. Every effort was made to provide a common
  484.          and more 'user friendly' program interface. Error handling and
  485.          recover was enhanced to better serve you, the user. The final
  486.          product hopefully reflects our efforts to provide you with a
  487.          'fine quality tool' to use to increase your productivity.
  488.  
  489.           However, as with any major effort, our testing cannot be exhaustive
  490.          enough, as we would want, to provide a 100% error free product.
  491.  
  492.           We welcome your comments, complaints and suggestions as to what
  493.          is wrong, right or could be better. Again thanks and enjoy.
  494.  
  495.  ***************************************************************************
  496.  
  497.  
  498.                           IN CLOSING
  499.                           ----------
  500.  
  501.        See the registration form at the end of this documentation, if you
  502.       want to become a registered user of the 'full featured' version of
  503.       this product.
  504.  
  505.      THIS IS A PRODUCT of DOWNLINK SYSTEMS INC and A $25 CONTRIBUTION IS ASKED
  506.      BUT IS NOT REQUIRED..PLEASE PASS THE PROGRAM ON IN ITS UNMODIFIED VERSION
  507.      ONLY.
  508.  
  509.            WE HOPE THIS LITTLE CONTRIBUTION WILL HELP YOU.
  510.  
  511.  
  512.  
  513.  Appendix A - Ordering
  514.  
  515.  
  516.  
  517.  
  518.                                    ORDER FORM
  519.  
  520.  
  521.  
  522.      Check which items you wish to purchase:
  523.  
  524.          (_) Noncommercial license for the use of BASICAID.
  525.  
  526.          (_) Commercial license for the use of BASICAID on __ computers.
  527.  
  528.          (_) Program update subscription service (not more than five
  529.              updates, does not include trivial changes), $35/year.
  530.  
  531.          (_) Payment of $_____ is enclosed (check or money order).
  532.  
  533.  
  534.              Signature: ________________________________
  535.  
  536.          _______________________________________________
  537.          Name
  538.  
  539.          _______________________________________________
  540.  
  541.  
  542.          _______________________________________________
  543.          Address
  544.  
  545.          ______________________   ________  ____________
  546.          City                     State     Zip
  547.  
  548.  
  549.      Send this completed form to:
  550.  
  551.                                  Downlink Systems Inc.
  552.                                  c/o D. Conner
  553.                                  1377 K STREET N.W.
  554.                                  SUITE 189
  555.                                  WASHINGTON D.C. 20005
  556.  
  557.      For program disk orders outside the U.S., please add an additional $5,
  558.      and enclose an international money order payable in U.S. currency.
  559.  
  560. ======================== end  of documentation ==============================
  561.